Skip to content

feat(desktop): 从选中文字学习,在其他应用里改正的写法进入学习建议 - #260

Open
sunerpy wants to merge 3 commits into
mainfrom
feat/learn-from-selection
Open

sunerpy wants to merge 3 commits into
mainfrom
feat/learn-from-selection

Conversation

@sunerpy

@sunerpy sunerpy commented Nov 18, 2026

Copy link
Copy Markdown
Owner

目标

测试用户反馈(2026-11-18):识别和 AI 润色都没有改对的错误,学习建议学不到。说「Qwen 4 max」,识别和润色都写成「Quinn for max」,用户在应用里改正了,Voltip 不知道。

这个 PR 是计划「从修改中学习」的第一部分:从选中文字学习(用户决定 2026-11-18,D1–D5 已逐项确认)。实验功能「跟踪输入框里的修改」是第二部分,先在用户的电脑上实测各应用的输入框能不能读到,再单独出计划。手机端不做。不发版。

用户能看到的变化(电脑)

  • 设置 → 快捷键:新增「从选中文字学习」,默认未设置,与听写、语音编辑、复制上一条结果的快捷键互不相同。纯 Wayland 下绑定 voltip-desktop --learn-selection。
  • 在其他应用里改正听写结果后,选中改好的文字按这个快捷键:悬浮窗显示「已记下 1 处改动:Quinn for → Qwen 4」,可以「加入词典」(改动里有 1 个字或 1–2 个字母的写法时只有「查看」)、撤销、查看,停 8 秒;没学到时说明原因(没有选中、终端、没找到对应的听写、历史记录关闭时带「打开设置」等)。
  • 词典 → 学习建议:每组写法标出来源「润色」「你的修改」;默认范围改名「推荐」,包含只出现 1 次的修改;只改了 1 个字的中文写法带上相邻的字(「非书 → 飞书」,以前是「非 → 飞」)。快捷键未设置时说明卡里有「设置快捷键」。
  • 历史详情:被改正过的记录多一行「之后改成」,可以移除。

改动

  • 核心(voltip-core):Settings.learn_hotkey 与四方互斥;CoreCommand::LearnSelection 与 runtime/learn.rs(探针 → 终端不按键 → 复制选区 → 最近 50 条听写 → 保存修改 → 计算组合 → 通知);vocabulary/learn.rs(对齐、相似度、选记录、可学的改动);HistoryEntry.corrected、HistoryStore::set_corrected、recent_texts 带出修改、搜索文本;学习建议的第二个来源(from_edits、edited、edit_picks);mcp::candidates 的单字扩展(scan / widen / Replay);UiState.learn_notice 的排队与计时(结果卡片在时排队,新听写开始时清掉,悬浮窗关闭时不建通知)。
  • 桥接与契约:新命令和事件,zod schema,IPC 夹具重新生成;两个手机壳把新命令列为仅电脑。
  • 桌面壳:快捷键注册(X11 / XWayland 松开后触发,其余按下触发)、--learn-selection、悬浮窗的 learned 状态、open_suggestions、open_privacy、history_clear_corrected。
  • 前端:设置页的快捷键行、悬浮窗卡片、学习建议的来源标记与「推荐」、历史详情的一行;MockBackend 同样的语义;中英文文案。
  • 文档:docs/dictation.md 新增 §35,改写 §16.10、§25.4;docs/acceptance.md、docs/threat-model.md;站点中英文的词典、快捷键、隐私页;重拍 dictionary-suggestions-{zh,en}-light.webp(mock 的示例记录加了两条带修改的听写,截图里能看到两种来源)。
  • CI:smoke-desktop 加装 python3-tk,跑 X11 的两个选区复制测试;冒烟脚本走一遍从选中文字学习。

与计划不同的地方

  • 真机复制测试放进 voltip-focus 已有的 focus_windows.rs / focus_macos.rs,没有在 voltip-inject 下新建 selection_windows.rs / selection_macos.rs:那两个测试已经会打开记事本和 TextEdit,CI 已经给 macOS 的测试二进制授予辅助功能权限,跑在同一步里。
  • 「打开设置」新增壳命令 open_privacy:计划写的是沿用学习建议页的按钮,但悬浮窗不能让主窗口换页,做法与「查看」的 open_suggestions 相同。
  • 冒烟测试发现一处匹配问题,已修复:错词在听写末尾、与正确写法没有相同的字时,平局取了最短的候选,「Voltip 冒烟注入」改成「Voltip 冒烟测试」存成了「Voltip 冒烟测」。现在平局先取词数与原写法最接近的(回归测试 regression_an_end_replacement_with_nothing_in_common_keeps_every_character,修复前按冒烟日志的方式失败)。§35.4 写明了这条规则。

改了期望的已有测试

  • 单字扩展是有意改规则(计划 4.4):原来期望「非书 → 飞书」汇总为「非 → 飞」的测试(core 的 suggest / mcp、bridge、shared 的 suggestions / mock、词典页),输入不变,期望改成扩展后的写法。扩展前忽略的单字组合仍然挡住扩展后的组合,有测试覆盖。
  • settings::tests::regression_the_smoke_scripts_write_the_current_settings_schema:smoke-dictation.sh 的设置模板多了可选的 learn_hotkey,测试加上这个占位的替换。规则(冒烟脚本写的是当前的设置格式)不变,现在也检查 learn_hotkey 这个键。
  • mock-backend.test.ts「the sample takes for screenshots …」:截图用的示例记录多了两条带修改的听写,次数随之改变;测试仍检查有出现 2 次及以上和只出现 1 次的建议,并新增检查「你的修改」。
  • 悬浮窗的失败文案「没能读取选中的文字」改为「无法读取选中的文字」(文案规范检查)。

测试

  • make verify 在 b5f9314 上通过(dirty_paths=0,rustc 1.98.0):Rust 过滤后的行覆盖率 92.91%(门槛 90%),桌面前端 97.5%,手机 97.69%,其余门禁全部 exit 0。

  • 另外单独跑了 cargo test --workspace --all-targets --no-fail-fast 与各前端包的全部测试,均通过。

  • 真机:

    • X11:两个选区复制测试本机连跑 40 次、32 核满载时 100 次,全部通过;scripts/smoke-desktop-linux.sh 本机通过(日志 learn selection outcome="learned",history.sqlite3 里那条记录的 corrected 是选中的文字,剪贴板放回哨兵内容,悬浮窗显示通知)。
    • Windows(hooks-windows)与 macOS(macos 的 Apple 芯片一路)的复制检查只能在 CI 上跑;macOS 合并前用 gh workflow run ci.yml --ref feat/learn-from-selection 触发。Windows 测试已用 cargo xwin clippy -D warnings 编译检查。
    • 本机 Xvfb 上,在真实应用里点了卡片的五个按钮(debug 构建,环境与冒烟脚本相同):「加入词典」后词典文件出现「测试」(曾听成「注入」),「撤销」后删除,× 后悬浮窗隐藏,「查看」后主窗口打开学习建议,历史记录关闭时「打开设置」打开「隐私与历史」。第一轮里应用在点「查看」前后无日志地退出过一次,之后三轮按相同顺序没有复现,原因没有查明。
  • 不需要 make refine-eval:提示词和预设都没改。

识别和 AI 润色都没有改对的错误(「Qwen 4 max」识别成「Quinn for max」),
学习建议以前学不到:它只比较识别原文和润色结果。现在用户在应用里改正后,
选中改好的文字按「从选中文字学习」的快捷键(默认未设置),Voltip 用复制键
读出选区,在最近 50 次听写里找到它改正的记录,把改后的文字存进这条历史
记录,改动作为「你的修改」进学习建议;悬浮窗显示记下的改动,可以一键加入
词典、撤销、查看。全程只逐字比较,不调用 AI(docs/dictation.md §35)。

- 核心:Settings.learn_hotkey 与四个组合键互斥;CoreCommand::LearnSelection
  与 runtime/learn.rs;vocabulary/learn.rs 的匹配与可学的改动;
  HistoryEntry.corrected 与 set_corrected;UiState.learn_notice 的排队与计时。
- 学习建议:第二个来源(from_edits、edited),「推荐」包含只出现 1 次的修改;
  中文单字的改动带上相邻的字(「非书 → 飞书」不再汇总为「非 → 飞」),
  MCP 的 vocabulary_candidates 同样。
- 桌面:快捷键注册(X11 松开后触发)、--learn-selection、悬浮窗的 learned
  状态、open_suggestions / open_privacy、设置页的快捷键行、历史详情的
  「之后改成」与移除。
- 真机测试:X11 的两个选区复制测试接入 CI;记事本与 TextEdit 的复制检查;
  Linux 冒烟测试走一遍完整流程。
- 文档:dictation §35、§16.10、§25.4,验收清单,威胁模型,站点中英文页面
  与学习建议截图。
@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.75216% with 150 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
apps/desktop/src-tauri/src/hotkey.rs 38.33% 37 Missing ⚠️
crates/voltip-core/src/runtime/learn.rs 87.44% 27 Missing ⚠️
apps/desktop/src-tauri/src/overlay.rs 50.00% 12 Missing ⚠️
packages/shared/src/mock-backend.ts 82.25% 6 Missing and 5 partials ⚠️
apps/desktop/src/pages/Overlay.tsx 83.01% 2 Missing and 7 partials ⚠️
crates/voltip-core/src/mcp/candidates.rs 95.94% 9 Missing ⚠️
packages/shared/src/quick-fix.ts 78.04% 1 Missing and 8 partials ⚠️
crates/voltip-core/src/vocabulary/learn.rs 97.97% 8 Missing ⚠️
apps/desktop/src-tauri/src/lib.rs 82.50% 7 Missing ⚠️
packages/shared/src/suggestions.ts 92.39% 0 Missing and 7 partials ⚠️
... and 8 more

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #260      +/-   ##
==========================================
- Coverage   93.58%   93.52%   -0.07%     
==========================================
  Files         489      491       +2     
  Lines       85908    87381    +1473     
  Branches     4909     5011     +102     
==========================================
+ Hits        80398    81722    +1324     
- Misses       4841     4962     +121     
- Partials      669      697      +28     
Flag Coverage Δ
rust 93.77% <91.59%> (-0.05%) ⬇️
web 92.27% <87.38%> (-0.13%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
apps/desktop/src/app/router.tsx 96.38% <100.00%> (+0.04%) ⬆️
apps/desktop/src/app/tray-requests.ts 83.33% <100.00%> (ø)
...pps/desktop/src/pages/dictionary/useSuggestions.ts 92.35% <100.00%> (ø)
apps/desktop/src/pages/history/DetailParts.tsx 98.27% <100.00%> (+0.23%) ⬆️
apps/desktop/src/pages/history/HistoryDetail.tsx 86.64% <ø> (ø)
apps/desktop/src/pages/settings/Hotkey.tsx 97.64% <100.00%> (+0.40%) ⬆️
apps/desktop/src/shell/Shell.tsx 94.49% <100.00%> (+0.32%) ⬆️
crates/voltip-core/src/dictation/engine.rs 97.33% <100.00%> (-0.09%) ⬇️
crates/voltip-core/src/dictation/fakes.rs 98.60% <100.00%> (+<0.01%) ⬆️
crates/voltip-core/src/history/derived.rs 100.00% <100.00%> (ø)
... and 36 more

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

- macOS 的终端里同样不复制、不学习:学习改用包括 macOS 终端的表
  (insert_check::holds_program_output),语音编辑的表在 macOS 上是空的。
- 选区复制一次只做一次:从保存到放回剪贴板持有进程锁,连按两次快捷键或
  学习与语音编辑同时复制时,不会把用户的剪贴板读成选区或弄丢。
- 已改正过的记录同时与改后的文字和插入的文字比较;改后的文字与选区没有
  相同的词时,以插入的文字为基准(选中原文撤回整处修改)。
- 修改来源的 via 增加 follow(以后的实验功能写入),这个版本能读取。
- 学习建议:用户修改每条记录每组只算 1 次;跳过的带修改记录也计入
  edited;只有修改、没有新写法时,空状态按比较过的记录写。
- 「查看」「打开设置」也让通知重新停留 8 秒(learn_notice_keep)。
- 「已忽略」的表头改为「识别结果 → 正确写法」。
已改正过的记录与改后的文字、插入的文字都对齐时,用相似度更高(一样高时
覆盖选区更多)的那个重建;胜出的是插入的文字时,把对齐的范围对到改后的
文字里替换,范围以外的旧修改照样保留。选区在下一个词之前结束时,保留原来
那里的空格(以前会拼成「Qwen 4 maxis great」)。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant